home *** CD-ROM | disk | FTP | other *** search
/ Aminet 6 / Aminet 6 - June 1995.iso / Aminet / disk / misc / dev_handler1_4.lha / Device-Handler / device-handler.doc < prev    next >
Encoding:
Text File  |  1995-03-06  |  6.9 KB  |  174 lines
  1. Device-Handler                                                  Device-Handler
  2.  
  3.  $VER: Device-Handler 1.4 (22 Feb 1995)
  4.  
  5.  Original code was written by Matthias Scheler. The original
  6.  distribution archive of Matthias has been included.
  7.  
  8.  
  9.  NAME
  10.     Device-Handler - UNIX-like raw device access
  11.  
  12.  WARNING
  13.     This software is intended for advanced users only. I *strongly*
  14.     recommend all people who do not understand every detail given
  15.     herein to obtain further information about ->AmigaDOS-Devices
  16.     and ->Handlers and their implementation on top of ->Exec
  17.     device drivers.
  18.  
  19.     ** WRONG USAGE OF THIS SOFTWARE WILL MOST LIKELY RESULT IN **
  20.     ** SEVERE LOSS OF DATA!                                    **
  21.  
  22.     As this software is freeware in cases of data disruption you
  23.     will find _nobody_ being responsible except yourself. Especially
  24.     Matthias and me reject any liability.
  25.  
  26.  FUNCTION
  27.     Amiga Users often put a jealous glance to the UNIX world, were
  28.     raw device access is as simple as nowhere else. Several solutions
  29.     to fix this for Amigas have been provided in the past. One of these,
  30.     the DEV: handler by Matthias Scheler, has been taken to base this
  31.     software on.
  32.  
  33.     Specifically, the original DEV: has the considerable drawback that it
  34.     only worked with devices that supported the ->TD_GETGEOMETRY
  35.     ->IORequest. Unfortunatly a lot of harddisk- (and other) drivers don't
  36.     implement this command.
  37.  
  38.     So I decided to derive the Exec-device selection from on the AmigaDOS
  39.     stream name in such way, that the user provides the Name of an
  40.     AmigaDOS Handler instead of the Exec-Device. There are system conform
  41.     ways to find out on top of which Exec-device an AmigaDOS handler is
  42.     running, so why not leaving this job to the DEV:-Handler ?
  43.  
  44.     With my DEV: enhancement, you may type things like "DEV:df0" or
  45.     "DEV:dh0", you get the general idea. Further improvements include the
  46.     ability to limit the total size which is allowed to read or write, and
  47.     to specify the low- and high cylinders to be used.
  48.  
  49.     Note that the physical definition is completely retrieved from the
  50.     given handler name (e.g. dh0), so there are some implications:
  51.  
  52.        * Exec-device will be always correct
  53.        * Exec-device unit will be allways correspond to the unit
  54.          the AmigaDOS handler works on, releasing you from dealing whith
  55.          it and thus making the usage of DEV: _much_ safer!
  56.        * Exec-device OpenDevice() flags are always correct
  57.        * Exec-device buffer memory type is always correct
  58.        * Most often you will want to use DEV: for ->UNIX tar and will want
  59.          to start writing exactly at block 0. For most floppy-base devices
  60.          this will be correct automatically. In contrast, nearly every
  61.          harddisk contains a ->RigidDiskBlock and the actual partitions
  62.          are located behind this, usually having a low-cylinder of about 3.
  63.          To archieve the intended bahaviour, you should create a special
  64.          DOSDriver/mountlist entry, such as:
  65.  
  66.            RDH0:                       /* raw dh0 */
  67.               Device = scsi.device     /* change this accordingly */
  68.               Unit = 1
  69.               Flags = 0
  70.               Surfaces = 5
  71.               BlocksPerTrack = 17
  72.               LowCyl = 0 ;             /* specify here full range */
  73.               HighCyl = 1023           /* of cylinders */
  74.               Stacksize = 4000
  75.               Priority = 5
  76.               GlobVec = -1
  77.               BufMemType = 0
  78.            #
  79.  
  80.          Another way is to use the LOCYL stream name option. Again note:
  81.          Playing around with LOCYL or HICYL is a pretty dangerous thing.
  82.          It is always advised to write a dedicated mountlist/DOSDriver.
  83.  
  84.     Plead read also the original documentation of the DEV:-handler.
  85.  
  86.  STREAM NAME
  87.  
  88.     The stream name is constructed as following:
  89.  
  90.        DEV:<DOSHANDLER>[/<MAXLEN>][/LOCYL=<NUM>][/HICYL=<NUM>]
  91.  
  92.     During stream name processing, all slashes are removed, thus creating
  93.     a standard AmigaDOS ReadArgs()-style text line, as you know it from
  94.     all CLI-Programs (I suppose you deleted all those that don't use
  95.     ReadArgs() ;).
  96.  
  97.     Additionally, all dots ('.') which are not part of a quoted text, are
  98.     substituted by an equation symbol ('='). That comes in handy when using
  99.     the LOCYL or HICYL options. AmigaDOS strips all equations that are not
  100.     quoted. Thus, the command "type dev:df0/locyl=3" would lead to an error,
  101.     as the handler would get the text "dev:df0/locyl" instead of
  102.     "dev:df0/locyl=3". So, either use the dot or quote the whole stream spec.
  103.  
  104.     *Any* number which is to pass to the handler may start with '$' or '0x'
  105.     or '0X' to indicate hexadecimal notation (default is decimal). A
  106.     trailing 'M' tells the handler to interprete it as a mega-value,
  107.     (i.e. multiply by 1024^2) and 'K' to signal a kilo value (factor 1024).
  108.     All charactes are case-insensitive.
  109.  
  110.     The complete convenience of ReadArgs() applies to stream name
  111.     construction:
  112.  
  113.        The template is "DOSHANDLER/A,MAXLEN,LOCYL/K,HICYL/K"
  114.  
  115.        DOSNAME
  116.           A valid, AmigaDOS-device name such as DH0, df0, ... The device has
  117.           to be mounted, though.
  118.  
  119.        MAXLEN
  120.           optional: maximum length of bytes to read or write. The (final)
  121.           lo/hicyl may enclose a smaller space: the smallest space is always
  122.           used. This value _must_ appear anywhere behind DOSHANDLER.
  123.  
  124.        LOCYL
  125.           Starting cylinder read from/write to. If higher than the (final)
  126.           high cylinder, low cylinder is casted to high cylinder.
  127.  
  128.        HICYL
  129.           Ending cylinder. If higher than physical, physical is used.
  130.  
  131.     Some example stream names:
  132.  
  133.        DEV:df0
  134.        DEV:dh0/1024
  135.        DEV:dh0/1k
  136.        DEV:dh0/LOCYL=0
  137.        DEV:dh1/HICYL=1k/LOCYL=0M/20M
  138.        DEV:df0/$1000
  139.        DEV:df0/0x2000/LOCYL.4
  140.        "DEV:df0/0X200/LOCYL=4"
  141.  
  142.  AUTHOR
  143.  
  144.     Marius Gröger,
  145.     Bärstadter Str. 4
  146.     D-65307 Bad Schwalbach
  147.     email: mag@sysgo.de
  148.  
  149.  SOURCE
  150.  
  151.     The source code of "Device-Handler" has been written with the GoldED
  152.     text editor (© Dietmar Eilert). Text folds start with "/*F*/"
  153.     and end with "/*E*/".
  154.  
  155.     You may make any changes to the source for your own use.
  156.     If you consider them useful for everybody, tell me so I can
  157.     include them to the next public release.
  158.  
  159.     The documentation has been extracted with makedoc (© Stefan Ruppert).
  160.  
  161.  $HISTORY:
  162.  
  163.  22 Feb 1995 : 001.004 :  some bug-fixing
  164.  18 Feb 1995 : 001.003 :  made Write() working...
  165.  20 Dec 1994 : 001.002 :  + one task/multiple FileHandles
  166.                           + source-code rework
  167.                           + better stream name scanning by ReadArgs()
  168.                           + new option MAXLENGTH
  169.                           + new options LOCYL, HICYL
  170.                           + highly improved read/write operation
  171.  18 Dec 1994 : 001.001 :  changed stream name convention
  172.  08 Dec 1994 : 001.000 :  took over from Matthias Scheler
  173.  
  174.